.TH std::basic_string::at 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string::at \- std::basic_string::at

.SH Synopsis
   CharT& at( size_type pos );             \fB(1)\fP (constexpr since C++20)
   const CharT& at( size_type pos ) const; \fB(2)\fP (constexpr since C++20)

   Returns a reference to the character at specified location pos. Bounds checking is
   performed, exception of type std::out_of_range will be thrown on invalid access.

.SH Parameters

   pos - position of the character to return

.SH Return value

   Reference to the requested character.

.SH Exceptions

   Throws std::out_of_range if pos >= size().

   If an exception is thrown for any reason, these functions have no effect (strong
   exception safety guarantee).

.SH Complexity

   Constant.

.SH Example


// Run this code

 #include <iostream>
 #include <stdexcept>
 #include <string>

 int main()
 {
     std::string s("message"); // for capacity

     s = "abc";
     s.at(2) = 'x'; // OK
     std::cout << s << '\\n';

     std::cout << "string size = " << s.size() << '\\n';
     std::cout << "string capacity = " << s.capacity() << '\\n';

     try
     {
         // This will throw since the requested offset is greater than the current size.
         s.at(3) = 'x';
     }
     catch (std::out_of_range const& exc)
     {
         std::cout << exc.what() << '\\n';
     }
 }

.SH Possible output:

 abx
 string size = 3
 string capacity = 7
 basic_string::at

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to        Behavior as published              Correct behavior
   LWG 847 C++98      there was no exception safety       added strong exception safety
                      guarantee                           guarantee

.SH See also

   operator[] accesses the specified character
              \fI(public member function)\fP
   at         accesses the specified character with bounds checking
              \fI(public member function of std::basic_string_view<CharT,Traits>)\fP
